Historic, archived document 


Do not assume content reflects current 
scientific knowledge, policies, or practices. 


a 


“\ Department of 
4a) Agriculture 


<==” Forest Service 


<a, United States 
ER. 


Pacific Northwest 
Research Station 


Research Note 
PNW-RN-491 
October 1989 


Abstract 


Introduction 


System 
Requirements 


An Introduction to 
PC-TRIM 


John R. Mills 


The timber resource inventory model (TRIM) has been adapted to run on person: - a 
al computers. The personal computer version of TRIM (PC-TRIM) is more widely ~2 
used than its mainframe parent. Errors that existed in previous: versions of TRIM 
have been corrected. Information is presented to help users witli program input 

and output management in the DOS environment, to understand the differences 
between PC-TRIM and mainframe TRIM, and to avoid common mistakes that can 
lead to program-generated errors. 


Keywords: Timber resource inventory model (TRIM), inventory models, computer 
software. 


The personal computer timber resource inventory model (PC-TRIM) is an up- 
dated version of the original mainframe TRIM program. The PC-TRIM model 

is four separate programs that have been compiled to run on IBM-compatible 
personal computers. | Because of the growth in use of personal computers by 
forest analysts, PC-TRIM has more users than does the mainframe version. The 
publication written to support TRIM (Tedder and others 1987) was written for the 
mainframe version; but, the format of the input and output is the same for both 
models, so Tedder and others is also a reference for PC-TRIM users. This intro- 
duction to PC-TRIM is intended to supplement Tedder and others (1987) with the 
information necessary to use the model on a personal computer. It contains the 
system requirements and hard disk installation information; it is assumed the 
reader is already familiar with the DOS operating system. Differences between 
the PC and mainframe versions are discussed in the appendix. 


The PC-TRIM system consists of four programs written in the FORTRAN 77 
standard. The PC-TRIM programs have been compiled by using RM/FORTRAN™ 
version 2.4, (Ryan-McFarland Corp.). Running PC-TRIM on a microcomputer requires 
the following hardware and software: 


At least 400K bytes of memory for program execution. 

Hard disk, bernoulli drive, or memory disk of at least 1M byte. 
DOS 2.1 or later. 

Math-coprocessor chip (8087, 80287, or 80387). 


The use of trade, firm, or corporation names in this publica- 
tion is for the information and convenience of the reader. 
Such use does not constitute an official indorsement or ap- 
proval by the U.S. Department of Agriculture of any product 
or service to the exclusion of others that may be suitable. 


JOHN R. MILLS is a research forester, Forestry Sciences 
Laboratory, P.O. Box 3890, Portland, Oregon 97208-3890 


The PC-TRIM 
System 


This section contains a summary of the four PC-TRIM programs and their inputs and 
outputs. For more details see Tedder and others (1987). The following four programs 
make up PC-TRIM: 


Program Function 

BRUSCN.EXE Inventory data processor 

GRUSCN.EXE Growth, yield, and timber management data 
processor 

ACUSCN.EXE Harvest and simulation contro! data 


processor, matches inventory with manage- 
ment parameters 
TRIM.EXE Timber projection program 


The first three programs Process input files and each produces two output files; 

one for the user, and one for input to another program (see fig. 1). The process- 
ing includes a check for errors in identity codes, formatting errors, and value checks 
against preset limits. The program BRUSCN processes the input file containing the 
beginning timber inventory. The GRUSCN program processes the input file contain- 
ing the growth, yield, and timber Management parameters. The ACUSCN program 
has two functions: First it processes the timber harvest parameters. Second, it links 
the timber inventory data processed by BRUSCN and the appropriate growth and 
yield parameters processed by GRUSCN. The ACUSCN program produces the in- 
put file for the TRIM program. 


Figure 1 shows how a PC-TRIM simulation can be organized into two levels of ac- 
tivity. At the first level are the programs BRUSCN and GRUSCN: at the second are 
the ACUSCN and TRIM Programs. Both programs in level 1 must finish without er- 
rors before the programs in level 2 can be run. Programs in level 1 do not need to 
be run in a particular order. In level 2, however, ACUSCN must always be run be- 
fore TRIM, and both programs must be run for each new simulation. The programs 
in level 1 may not need to be rerun for every simulation; for example, if changes are 
made to just the ACUSCN input (harvests, report request, etc.), then only level 2 
needs to be rerun. 


Level 1 


BRURAF 


Level 2 


BIGRAF 


Figure 1—The organizational flowchart of a PC-TRIM 
simulation divided into two levels of activity. 


The PC-TRIM system is organized by input files, programs, and outputs, as shown 
in the following tabulation:<  - 


Level Input Program Output 

1 INVEN —> BRUSCN —> BRURAF, LIST.BRU 
CONTROL —> GRUSCN —> GRURAF, LIST.GRU 

2 BRURAF — 
GRURAF — 
HEADER > ACUSCN —> BIGRAF, LIST.ACU 
BIGRAF —> TRIM —> DETAIL, CALLS, OUTPUT, 


DUMP, CURRAF 


Output Files The BRURAF and GRURAF output files are direct-access binary files used in 
level 2 by the ACUSCN program. Because they are binary files, they cannot 
be altered in a regular text editor. The ACUSCN program will not run unless 
both the BRURAF and GRURAF files are Present (in the same subdirectory as 
HEADER). 


The LIST files contain an organized report of all input values. If a program en- 
counters input records out of order, values out of range, mismatched or missing 
inputs, or other errors, error messages or warning messages are written in the 
appropriate LIST file. 


The most important listing is the output LIST.ACU. It contains a report of the be- 
ginning inventory by GRU including stocking (inventory volume divided by yield 
table volume) calculated for each age class in each management intensity (that is, 
for each yield table). The user should become familiar with this report because it 
illustrates the relation between the yield table volume and the beginning inven- 
tory volume. At the bottom of the output file is the “tree report,” which accounts 
for each BRU, GRU, and ACU found in INVEN, CONTROL, and HEADER. In this 
report, the BRU’s making up each GRU are listed, and any BRU’s or GRU’s pres- 
ent but not matched are flagged. This is a good place to check to be sure that the 
identity codes are matching up and the inventories are being accounted for. 


The BIGRAF output file is a direct access binary file containing the compilation of 
all PC-TRIM inputs. This is the only input file for the TRIM program, and it must be 
present for TRIM to execute. 


The CURRAF output file is a direct-access binary file created by the TRIM program 
during the simulation. It is used by the TRIM program to store and update the 
projected inventory as the simulation progresses. This file contains the database from 
which TRIM reports are generated. It cannot be edited with a text editor, and it has 
no value after a simulation (unless the user develops a special program to read it). 


? Also see figure 2 in Tedder and others (1987). 


Setting Up Your 
System 


The DETAIL output file is the simulation report requested by the user (on HEADER 
card types 03 and 05). If a high level of detail was requested, this file may be very 
large (that is, a report of each GRU in each period). Printing this file for each run of 
TRIM can be time consuming. | recommend that after each simulation the user first 
print (or check in an editor) the last section in this file titled “SUMMARY REPORTS.” 
This section contains a condensed record of the simulation results; that should pro- 
vide enough information for the user to determine whether the simulation ran suc- 
cessfully. Then, if the file is needed, it can be printed. 


- The CALLS output file contains a listing of the subroutines called by the TRIM 


program as the simulation progressed. This file can usually be ignored; however, 
if the TRIM program aborts, this file contains error messages (at the bottom) that 
may indicate the source of the problem. 


The OUTPUT output file is a simple record of the simulation progress by projec- 
tion year. It can usually be ignored, but if an error occurs during the simulation, check 
it for an informative error message. 


The DUMP output file is normally empty. This file is for the convenience of the user 
attempting to modify and test new program code. There are three different dump 
subroutines in the TRIM program, but with the exception of RETURN statements, 
they are empty. A user attempting to modify and test the TRIM program code can 
use the DUMP output file as a place to write diagnostic output (that is, values of 
particular variables at the completion of each subroutine). If GRU card type 03 has 
been set, the DUMP subroutines are called at the end of each program subroutine 
or if an error is detected, or both. This is a practical feature, but it is up to the user 
to customize the DUMP subroutines with write statements to get diagnostic output. 


Note: The ASCII (American National Standard Code for Information Interchange) 
input files are 80 columns wide, and the ASCII output files are 122 columns wide. 
“Condensed” print mode is required to print the output files on an 80-column printer. 


The following section is provided to help users efficiently run the PC-TRIM programs 
on a microcomputer. The programs themselves are large, and they create numerous 
large output files. To avoid system errors, the computer's CONFIG.SYS file should 
contain the following minimum parameters: 


Buffers = 20 

Files = 20 

Fcbs = 20,20 (if using DOS 3.x) 

Break = on (not required but recommended) 


If the CONFIG.SYS file does not contain these settings, add them and reboot 
the system before attempting to run PC-TRIM programs. These settings should 
not interfere with the operation of any other software, so they can remain in the 
CONEFIG.SYS file when PC-TRIM is not being used. If these parameters are un- 
familiar, reference “configuring your system” in your DOS manual. (If “buffers” 
and “files” are currently larger than 20, they do not need to be changed.) 


Batch Files 


Using RAM Memory 


To run any of the PC-TRIM programs, a special parameter is required to allow Ryan- 
McFarland FORTRAN to read and write long direct-access input and output records. 
The following parameter needs to be entered on the command line just after the 
program name: /R 35000. To run the BRUSCN program enter: BRUSCN/R35000° 
(either upper or lower case). Because this is an awkward command, it makes sense 
to use batch files to save keystrokes (and errors); for example, the batch file called 
GOBRU needs to contain a one line entry: BRUSCN/R35000. To easily run level 2, a 
batch file called LEV2 could contain the following: 


ACUSCN/R35000 and TRIM/R35000. 


When ACUSCN finishes execution, TRIM starts. (If ACUSCN finishes execution after 
detecting errors, the TRIM program, by default, will abruptly stop.) 


Batch files can be developed to erase unneeded files after a run. Each new simula- 
tion creates a new LIST.ACU, BIGRAF, CURRAF, OUTPUT, CALLS, DUMP, and 
DETAIL file. Maintaining files can be made easier by using one batch file to delete 
these files after a simulation (be sure to first rename any files that should be saved; 
that is, LIST.ACU and DETAIL). If you are unfamiliar with batch files, see your DOS 
manual. Batch files save keystrokes for many repetitive tasks. 


The PC-TRIM programs are “disk intensive,” meaning that a program will spend a 
large fraction of the total processing time reading and writing files on the disk. An 
increase in the disk access speed can significantly reduce the time required for PC- 
TRIM to complete a simulation. This can be accomplished by using PC-TRIM on 
computers with fast disk access times. The programs will run fastest when random 
access memory (RAM) configured as a disk drive is used. This is where a PATH 
statement (described below) will really be useful, because a RAM drive is usually 
limited in size (the PC-TRIM programs take up about 500K bytes). A RAM drive may 
require an addition of an expanded (or extended) memory board to the computer. For 
the execution of PC-TRIM, a RAM drive of 3 to 4 megabytes should be sufficient; 
however, a simulation using 50 or more GRU’s will require prudent file management. 


One final reminder concerning RAM drives; they lose all memory when the power is 
off. The inputs INVEN, CONTROL, and HEADER will need to be copied to the RAM 
drive before the run. When the run is finished, copy the inputs back to the hard disk 
only if they need to be saved (that is, if they were edited after being copied to the 
RAM drive). If DETAIL is worth keeping, it can be renamed and copied to a subdirec- 
tory on the hard disk. All files left on the RAM disk will be erased when the computer 
is turned off. 


3 The minimum record-length parameter required for each 
program is different; that is, BRUSCN will run with a record- 
length parameter of 8000. The value 35000 is slightly more 
than the minimum required for TRIM to run, and larger 
values cause no problems; so for simplicity, the same num- 
ber was used for all programs. 


File Handling 


The PC-TRIM programs require and create 14 input and output files. Some users 
may want to simplify file management by using DOS subdirectories to separate 
the PC-TRIM programs and batch files from the input and output files. Subdirec- 
tories should be used to keep related sets of inputs and outputs in one place. 


The program files can be stored apart from the inputs and outputs by invoking the 
DOS PATH statement. The PATH statement will act to bridge subdirectories so 
that the program and batch commands will operate as if they reside locally. It is 
possible to run PC-TRIM from any subdirectory (or disk drive) as long as the input 
files (INVEN, CONTROL, and HEADER) reside in the “current” directory. A PATH 
statement can be issued from the keyboard or added to the AUTOEXEC.BAT file. 
The following example illustrates how to create subdirectories for the program and 
input files, and how to add the PATH statement to the AUTOEXEC.BAT file: 


First create the subdirectories PCTRIM and DATA with the commands 
MD\PCTRIM and MD\DATA . 


Modify the path command in the AUTOEXEC.BAT file to contain the string: 
C:\PCTRIM . 

A change to the path statement might look like this: 

Before: path c:\dos;c:\fortran 

After: path c:\dos;c:Mortran;c:\petrim 


if there is no PATH command in the AUTOEXEC.BAT file, see the DOS manual and 
create one. A PATH statement will allow the DOS command (COM) files to be stored 
together in a subdirectory rather than in the root directory. Be sure to include that 
subdirectory in the PATH statement. The modification to AUTOEXEC.BAT will remain 
transparent; PATH can be invoked at all times without affecting the performance of 
other applications. 


Copy the PC-TRIM EXE and any BAT files into the C:\PCTRIM subdirectory, and 
copy the input files (INVEN, CONTROL, HEADER) into the subdirectory C:\DATA . 
The PC-TRIM programs can now be run from the \DATA subdirectory by using the 
appropriate commands (BRUSCN/R35000, or GOBRU, etc.). All PC-TRIM output 
files will be written to the \DATA subdirectory. With the use of the PATH command 
shown above there is no restriction as to the subdirectory, or drive, which must be 
current to run PC-TRIM; for example, a user can insert a floppy disk in drive A:, 
which contains the INVEN file, and issue the GOBRU command from drive A:. The 
BRUSCN program located in C:\PCTRIM reads INVEN from A: and writes the out- 
puts to drive A:. Again, this procedure works well with a RAM drive for fastest per- 
formance. The PC-TRIM programs will load into memory (used by the operating 
system) from the hard disk, and all file reading and writing takes place on the RAM 
memory disk rather than on a physical disk. 
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A word of caution. Create a logical system to rename the input and output files. 
With a single simulation involving 14 files that always have the same names, it 

iS easy to become confused over the differences between sets of inputs and out- 
puts. | recommend using one subdirectory or drive to make most simulations. This 
is much the same procedure followed when using a RAM drive in which to run the 
programs. Create inputs in a separate subdirectory and copy them to a scratch sub- 
directory dedicated to input and output files. After the simulation, edited inputs and 
Savable outputs can be renamed and copied into other subdirectories for Saving. 
When a session is finished, CURRAF and BIGRAF should be deleted because they 
will have no further use and they occupy disk space. 
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The origin of PC-TRIM can be traced back to the model developed for use in a study 
of the timber resource in Oregon (Beuter and others 1976). That model became 
known as TREES and was well documented by Tedder and others (1980). Tedder 
began the development of a new model based on the TREES system in 1981, this 
model became known as TRIM. The onginal TRIM model was compiled on a CYBER 
170/720 at Oregon State University. The conversion to a PC version began in 1986 
by K. Norman Johnson of the College of Forestry, Oregon State University. 


Since the development of initial microcomputer version, both the mainframe and PC 
versions of TRIM have been modified. The mainframe version was modified for use 
in the fourth forest study (U.S. Department of Agriculture 1988) to accommodate 
input from a complex area-change model. The sequencing of growth and harvest 
was changed so growth would be reported with the beginning of the period inventory. 
Figure 6 in Tedder and others (1987) represents the fourth forest version. 
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Changes to PC-TRIM 


Rounding Problems 


The differences between the PC version and the southern study version include the 
sequencing of growth and harvest and the reporting of growth-on-harvest. The result 
of these differences is that, given the same inputs, the two models will produce differ- 
ent projections of inventories. 


The PC version uses the same sequencing of harvest and growth as the original 
mainframe version. The biggest difference between PC-TRIM and the southern 
study version is the sequencing of activity in the “zero-period” or starting period. 
Compare figure 2 in this paper and figure 6 in Tedder and others (1987). In PC- 
TRIM, when period equals zero, there is a shortcut across the loop and the first 
action is the summing of current (or beginning) inventory. In figure 6 (Tedder and 
others 1987) the shortcut does not exist; instead it appears that when period equals 
zero, harvest allocated first. But figure 6 does not clearly represent the activities in 
period zero. In the starting period, the first time through the loop, harvest is set to 
zero so that harvest and regeneration of harvested acres is skipped. The projec- 
ted period starts with area change, thinning, and growth, with the effect that har- 
vest and regeneration occur at the end of the period. 


In PC-TRIM the beginning inventory is summed, harvest occurs, and at the end 
of the period, growth takes place. Because harvest occurs at the start of the per- 
iod, growth-on-harvest must be used if it is assumed that harvest will occur over 
the entire period (or at the middle of the period). Growth-on-harvest is an option 
with southern study TRIM, but because a full period of growth is applied to the 
inventory before harvest, it is not logical to use it. 


The PC-TRIM program was modified to allow for donor-acre shifts to occur before 
harvest in the first period (allowing for the option of volume to be captured and 
partially fulfill the first harvest request). The subroutine DONORS is executed 

at the start of a period (after the beginning inventory is summed) rather than 

after harvest (see fig. 2 in this paper and fig. 6 in Tedder and others [1987]). 


A PC does not necessarily carry the same precision or use the same rounding 
scheme as a mainframe computer. A mainframe such as the CYBER has a 60-bit 
word length that allows more places of precision than does a microcomputer with 
a 32-bit (single precision) unit length. The TRIM program contains many error- 
checking algorithms that often depend on a high level of precision (double preci- 
sion). The single precision and rounding that takes place on the microcomputer 
will sometimes cause problems for GRU card types 28 and 38 in the program TRIM. 
Card type 28 is an Ml-shifting card that might have portions summing to 1.00. The 
GRU card 38 allocates a proportion of the harvest to an age class, and the total 
proportions should sum to 1.00. (See Tedder and others [1987] for more details 
about these GRU card types.) While TRIM is running, it checks the total propor- 
tion of acres shifted or harvested; if they sum to more than 1.0000, an error mes- 
sage is written to the CALLS file and the program aborts. 
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Figure 2—Flowchart of the PC version of the TRIM program. 
The names of subroutines are in capital letters. 


a 


| 


Growth Carryover 


These errors can be avoided by adjusting proportions (within a GRU) so that the 
total is slightly less than 1.0000. In the case of GRU card 28, the error may occur 
when 100 percent of the acres are shifted out of any one management intensity (MI) 
category. The problem can be eliminated by reducing the acreage shift by less than 1 
percent; for example, if the total shift out of Ml 1 equals 1.00, then lower one card 28 
so the that new total is equal to 0.9999 . The same strategy applies to GRU card 
type 38; the sum of the harvest proportions should be slightly less than 1.00 (0.9999 
works fine), however, if the difference between 1.00 and the lower sum is too great, 
the GRUSCN program will indicate an error. This solution to the error-checking prob- 
lem should not significantly alter projection results. 


For versions of PC-TRIM older than January 1989, growth-on-harvest can be incor- 
rectly summed into the wrong ACU’s. This will happen only when multiple ACU’s are 
used and the number of harvest values in the HEADER file exceeds the number of 
periods in the simulation. The model will always attempt to make one extra harvest, 
so if there are eight harvest values in HEADER but the simulation is for five periods, 
the model will make a total of six harvests. The sixth harvest represents an action 

in the period beyond the last reported inventory. (In the final period of the simulation, 
the subroutines ALOCAT and REPORT are called from the subroutine PROPRT. 
This is not shown in fig. 2.) A problem occurs because growth-on-harvest is calcu- 
lated for the extra harvest. The regular growth routine does not get called, and this 
growth gets carried into the next ACU where it is incorrectly summed into the growth 
reported for the final period. To avoid this problem do not enter more harvests than 
there are periods. In the case above, three zeros can be entered to fill out the eight 
harvest entries. 
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